Developer CD Series 1999 January: Mac OS SDK/Dev.CD Jan 99 SDK1.toast/Development Kits/AppleScript/Development Tools/Tools Goodies/AEGizmos 1.4.1/Documentation/AEStream Doc.dp

Common Ground | 1995-03-20 | 27.5 KB | 336 lines | [CGDC/CGVM]

Palatino
Apple Events
 Stream Library
AEGizmos Version 1.4
Jens Peter Alfke
20 March 1995
 Apple Computer, Inc. 1991
New York
Palatino
The Apple Event Stream Library
20 March 1995
Page
Contents
Contents
)7 ................................
)h ................................
)h ................................
Introduction
)M ................................
)h ................................
...............................
OK, What Is It?
s In It For Me?
Just How Stable Is It, Anyway?
What Are All Those Files?
Disclaimer
AEStream Functions
){ ................................
)h ................................
.................
Opening and Closing a Stream
Writing Descriptors
Writing Lists
Writing Records
#Writing Key Descriptors For Records
The Header Files
)g ................................
)h ................................
.......................
AEStream.h
AEStream_CPlus.h
New York
Palatino
The Apple Event Stream Library
20 March 1995
Page
Introduction
OK, What Is It?
LThe Apple Event Manager routines that assemble descriptors and parameters (I
speak here of
Courier
AECreateDesc
AECreateList
    AEPutDesc
AEPutParamDesc
et al
fMprovide very flexible random access at the expense of significant overhead in
Ispeed and memory. Constructing nested structures involves duplicating and
Lcopying a whole lot of data. In many cases, programs create descriptors in a
6more or less linear fashion, without many common subex
pressions. In such
fPsituations you could use a stream-like protocol and speed things up quite a bit.
MThat
s what the AEStream library does for you. It doesn
t use the Apple Event
PManager at all. Instead, it builds up a single descriptor from beginning to end.
OThe descriptor data stays all in one block and grows in discrete increments, so
-there will be far fewer Memory Manager calls.
s In It For Me?
Zapf Dingbats
ESheer, raw speed. It
s about three to four times as fast as using the
Apple
Event Manager routines.
@Code that builds nested descriptors will be simpler and clearer.
CSimpler cleanup; there
s only one stream object, not a multitude of
descriptors, to be disposed.
 How About Access From Pascal?
SAs far as I know, there
s no reason why you couldn
t call this library from Pascal,
whether the
THINK
)!5 variety. All you need to do is write a Pascal header
fQequivalent to AEStream.h. (Keep in mind that all the functions have use C calling
Vconventions.) If you write one, send it to me and I
ll include it in the next release.
Palatino
The Apple Event Stream Library
Page
20 March 1995
AEStream Functions
PENING AND
    LOSING A
TREAM
AEStream_Open
Courier
$OSErr AEStream_Open( AEStreamRef s )
AEStream_Open
)N* opens the stream structure pointed to by
 as a new, empty
NOstream suitable for writing a single (simple or nested) descriptor. You must do
8this before writing any data to the stream. For example:
AEStream myStream;
err= AEStream_Open(&myStream);
// more stream calls...
AEStream_OpenEvent
;OSErr AEStream_OpenEvent( AEStreamRef s, AppleEvent *aevt )
AEStream_OpenEvent
)l* opens the stream structure pointed to by
 for appending to
the existing Apple Event
+ (which was presumably created by a call to
AECreateAppleEvent
)l:.) You can then add parameters to the event by adding them
as key descriptors (see the
Writing Key Descriptors
 section.)
N6The stream takes posession of the Apple Event data in
; you can
t use it
NQdirectly until you close the stream. To ensure this, the descriptor pointed to by
/ parameter is cleared out to a null descriptor.
Zapf Dingbats
Warning
)D<Do not open a stream on an Apple Event that is in use by the
Apple Event Manager
$ the current event being handled, or
Palatino
The Apple Event Stream Library
20 March 1995
Page
9a pending reply
 or the AEM may become very unhappy with
your meddling.
Zapf Dingbats
AEStream_CreateEvent
Courier
OSErr AEStream_CreateEvent(
%AEStreamRef, AEEventClass, AEEventID,
?DescType targetType, const void *targetData, long targetLength,
$short returnID, long transactionID )
AEStream_CreateEvent
 first calls
AECreateAppleEvent
 to create a new Apple
f,event, then opens a stream on it by calling
AEStream_OpenEvent
AEStream_Close
3OSErr AEStream_Close( AEStreamRef s, AEDesc *desc )
AEStream_Close
 closes the stream. If
 , the data in the stream will be
fRdisposed with no questions asked. (Use this if you need to abort due to an error.)
;Otherwise, the finished descriptor will be copied into the
AEDesc
 pointed to by
4. If the descriptor is not finished, the error code
errAEStream_BadNesting
 will
be returned.
KIf you opened the stream on an Apple event, after the stream is closed the
f/parameter will contain a bona fide Apple event.
0After closing a stream, you can re-open it with
AEStream_Open
 and re-use it
new data, of course.
RITING
IMPLE
ESCRIPTORS
fMThese routines let you write data descriptors to the stream. Do not use these
Rroutines to write lists or records! You write those by using routines described in
following sections.
Palatino
The Apple Event Stream Library
Page
20 March 1995
AEStream_WriteDesc
Courier
ROSErr AEStream_WriteDesc( AEStreamRef s, DescType type, void *data, Size length );
AEStream_WriteDesc
)l6 appends an arbitrary block of data to the stream as a
descriptor, much like
AECreateDesc
AEPutPtr
AEStream_WriteAEDesc
:OSErr AEStream_WriteAEDesc( AEStreamRef s, AEDesc *desc );
AEStream_WriteAEDesc
)x4 appends a prepackaged Apple Event descriptor to the
stream
, much like
)>    AEPutDesc
. The descriptor
  is not disposed by the call; if
N:you don
t need it anymore, dispose it yourself by calling
AEDisposeDesc
N9AEStream_OpenDesc, AEStream_WriteData, AEStream_CloseDesc
9OSErr AEStream_OpenDesc(  AEStreamRef s, DescType type );
COSErr AEStream_WriteData( AEStreamRef s, void *data, Size length );
*OSErr AEStream_CloseDesc( AEStreamRef s );
*!OUse these three routines if you want to write a data descriptor piece by piece.
First call
AEStream_OpenDesc
, then call
AEStream_WriteData
 zero or more times to
N,write zero or more bytes of data, then call
AEStream_CloseDesc
 to end the
descriptor.
Palatino
The Apple Event Stream Library
20 March 1995
Page
RITING
f%AEStream_OpenList, AEStream_CloseList
Courier
*OSErr AEStream_OpenList(  AEStreamRef s );
*OSErr AEStream_CloseList( AEStreamRef s );
To write a list, call
AEStream_OpenList
)f(, write zero or more descriptors as list
elements, then call
AEStream_CloseList
)l%.  The descriptors can be simple data
f7descriptors (see above), lists, or records (see below).
RITING
ECORDS
f)AEStream_OpenRecord, AEStream_CloseRecord
;OSErr AEStream_OpenRecord(  AEStreamRef s, DescType type );
,OSErr AEStream_CloseRecord( AEStreamRef s );
To write a record, call
AEStream_OpenRecord
, write zero or more
key descriptors
(see below), then call
AEStream_CloseRecord
AEStream_OpenRecord
)r     lets you
fHspecify the type to which the record should be coerced; use the constant
typeAERecord
)H! if you want an uncoerced record.
AEStream_SetRecordType
=OSErr AEStream_SetRecordType( AEStreamRef s, DescType type );
Palatino
The Apple Event Stream Library
Page
20 March 1995
NNAt any time between opening a record and closing it, you can coerce the record
to a different type by calling
Courier
AEStream_SetRecordType
. (This is useful if you don
N?know what type to make the record until it
s time to close it.)
RITING
ESCRIPTORS
ECORDS
NNUse these functions to add elements to records, and to add parameters to Apple
events.
AEStream_WriteKeyDesc
:OSErr AEStream_WriteKeyDesc( AEStreamRef s, AEKeyword key,
)DescType type, void *data, Size length );
AEStream_WriteKeyDesc
)~4 writes a complete key descriptor. It
s identical to
AEStream_WriteDesc
 except for the
) parameter which specifies the keyword to
use for this descriptor.
AEStream_OpenKeyDesc
JOSErr AEStream_OpenKeyDesc( AEStreamRef s, AEKeyword key, DescType type );
AEStream_OpenKeyDesc
 is identical to
AEStream_OpenDesc
 except for the
NEparameter which specifies the keyword to use for this descriptor. Use
AEStream_CloseDesc
 to end the descriptor.
AEStream_WriteKey
8OSErr AEStream_WriteKey( AEStreamRef s, AEKeyword key );
Palatino
The Apple Event Stream Library
20 March 1995
Page
Courier
AEStream_WriteKey
)f; writes the keyword to be used by the immediately following
f3descriptor, list or record. The next AEStream call
 begin a descriptor
must be
_WriteDesc
    _OpenDesc
    _OpenList
_OpenRecord
 or you
ll get a
nesting error.
AEStream_WriteKey
)f@ is the only way to add a list or record as a field of a record.
s also useful if you are writing a record and want to call a subroutine that
writes a descriptor:
*err= AEStream_OpenRecord(s, typeAERecord);
"err= AEStream_WriteKey(s, kMyKey);
// this is the key
writeMyDescriptor(s);
// for this descriptor
err= AEStream_CloseRecord(s);
AEStream_OptionalParameter
AOSErr AEStream_OptionalParameter( AEStreamRef s, AEKeyword key );
Call
AEStream_OptionalParameter
/ to specify that the Apple event parameter with
fPthe given keyword is an optional parameter. (This means that the receiver of the
.event is not required to read that parameter.)
MThis function just adds the keyword to the optional-keywords attribute of the
Mevent. You can call it before, during or after adding the matching parameter.
@    >%^
('&:O
p 0p`P
xP(H`X
    temp.0001
N^ _\ON
Jens Alfke
Apple Computer
Microsoft Word
New York
Zapf Dingbats
Palatino
Courier
bPREC
nPRVS
zCAPN